Skip to content

docs: point the upgrade guide's Copilot checks at .github/skills - #5010

Merged
mnriem merged 2 commits into
github:mainfrom
yxshee:docs/upgrade-copilot-skills-path
Oct 19, 2026
Merged

docs: point the upgrade guide's Copilot checks at .github/skills#5010
mnriem merged 2 commits into
github:mainfrom
yxshee:docs/upgrade-copilot-skills-path

Conversation

@yxshee

@yxshee yxshee commented Oct 17, 2026

Copy link
Copy Markdown
Contributor

Description

The upgrade guide's troubleshooting step tells GitHub Copilot users to check ls -la .github/prompts/. On a default Copilot project that directory doesn't exist, so the documented check fails and suggests the commands were never installed.

Since #3976 (feat(copilot): default integration to skills), Copilot installs skills under .github/skills/ by default. .github/prompts/ (together with .github/agents/) only exists with the opt-in commands layout, --integration-options="--commands".

Reproduction with the current CLI:

$ specify init demo --integration copilot --ignore-agent-tools --non-interactive && cd demo
$ ls -la .github/prompts/
ls: .github/prompts/: No such file or directory
$ ls .github/
skills
$ ls .github/skills/
speckit-analyze
speckit-checklist
speckit-clarify
speckit-constitution
speckit-converge
speckit-implement
speckit-plan
speckit-specify
speckit-tasks
speckit-taskstoissues

With --integration-options="--commands", .github/ contains agents/ and prompts/ (speckit.analyze.prompt.md, …) instead.

Changes, all in docs/upgrade.md:

  • the verification step now runs ls -la .github/skills/, with a comment naming .github/agents/ and .github/prompts/ for the --commands layout
  • the three other places that list Copilot's command location now say .github/skills/

Heads-up: #4601 also edits the "permanently installed" sentence for a different reason (/speckit.x → /speckit-x), so whichever lands second has a one-line conflict.

Testing

  • Tested locally with uv run specify --help

  • Ran existing tests with uv sync && uv run pytest: docs-only change; no test reads docs/upgrade.md

  • Tested with a sample project (if applicable): the specify init --integration copilot reproduction above, with and without --integration-options="--commands"

  • npx markdownlint-cli2@0.23.2 docs/upgrade.md (the version pinned by DavidAnson/markdownlint-cli2-action v24.2.0 in lint.yml): 0 issues

AI Disclosure

  • I did not use AI assistance for this contribution
  • I did use AI assistance (fill in the disclosure below)

AI disclosure: Claude Code (model: Claude Opus 5.5, max reasoning effort, autonomous agent mode) opened this PR on behalf of @yxshee. A Claude Code subagent (same model, autonomous) found the drift by running the documented commands against the CLI and wrote the docs change. The lead agent reviewed the diff, ran markdownlint, and wrote this description. No human reviewed the change line by line before it was opened.

🤖 Generated with Claude Code

@yxshee @claude
docs: point the upgrade guide's Copilot checks at .github/skills
fc1f0e6 
Copilot has installed skills under .github/skills/ by default since github#3976
(feat(copilot): default integration to skills). .github/prompts/ is only
created by the opt-in commands layout (--integration-options="--commands"),
next to .github/agents/.

The upgrade guide still told Copilot users to verify their install with
`ls -la .github/prompts/`, which fails with "No such file or directory"
on a default `specify init --integration copilot` project, and it listed
.github/prompts/ as Copilot's command location in three other places.

Point those references at .github/skills/ and name the commands-layout
directories in the verification step.

Assisted-by: Claude Code (model: Claude Opus 5.5, autonomous)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@yxshee
yxshee requested a review from mnriem as a code owner October 17, 2026 19:02
@mnriem mnriem added the triage-can-wait Verdict: valid and in-scope but deprioritized; held behind the evidence gate label Oct 18, 2026
@mnriem
mnriem requested a max review from Copilot October 19, 2026 13:00
Copilot AI reviewed Oct 19, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The documentation matches Copilot’s default layout, with no blocking issues identified.

1 open issue
What changed in this PR

Aligns the upgrade guide with Copilot’s skills-first integration introduced in #3976.

Changes:

  • Updates Copilot directory references and checks to .github/skills/.
  • Notes the alternative commands-layout directories.
File Description
docs/​upgrade.md Corrects Copilot installation paths and troubleshooting guidance.

Review effort: Max

Comment thread docs/upgrade.md Outdated
@yxshee @claude
docs: name the Copilot commands-layout check in the upgrade guide
dbd7cd9 
Projects created before Copilot defaulted to skills keep the commands
layout when upgraded (see test_upgrade_preserves_historical_copilot_
commands_without_options), so `ls .github/skills/` reports a missing
directory for them. Give the commands layout its own check alongside the
skills one.

Assisted-by: Claude Code (model: Claude Opus 5.5, autonomous)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@yxshee

yxshee commented Oct 19, 2026

Copy link
Copy Markdown
Contributor Author

Review round 1, posted on behalf of @yxshee.

Addressed the Copilot review note on docs/upgrade.md: the troubleshooting step now has a separate check for the commands layout (ls -la .github/agents/ .github/prompts/). It names both cases, --integration-options="--commands" and projects created before skills became the default that were upgraded since, as covered by test_upgrade_preserves_historical_copilot_commands_without_options. Commit: dbd7cd9. markdownlint-cli2 0.23.2: 0 issues.

AI disclosure: written and pushed by Claude Code (model: Claude Opus 5.5, max reasoning effort, autonomous agent mode); the docs edit and this comment are AI-generated.

🤖 Addressed by Claude Code

@mnriem
mnriem requested a max review from Copilot October 19, 2026 13:51
Copilot AI reviewed Oct 19, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The documentation matches the supported layouts, with no blocking issues.

No open issues 🎉

1 resolved since last review

Review effort: Max

@mnriem
mnriem merged commit 9bc5c9d into github:main Oct 19, 2026
16 checks passed
@mnriem

mnriem commented Oct 19, 2026

Copy link
Copy Markdown
Collaborator

Thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@mnriem mnriem Awaiting requested review from mnriem mnriem is a code owner

Assignees

No one assigned

Labels

triage-can-wait Verdict: valid and in-scope but deprioritized; held behind the evidence gate

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@yxshee @mnriem